<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.2.6" />
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revision {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble,
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock {
  margin-right: 0%;
}
div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock > div.content {
  padding-left: 2.0em;
}

div.attribution {
  text-align: right;
}
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.verseblock div.content {
  white-space: pre;
}

div.imageblock div.content { padding-left: 0; }
div.imageblock img { border: 1px solid silver; }
span.image img { border-style: none; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
div.olist > ol {
  list-style-type: decimal;
}
div.olist2 > ol {
  list-style-type: lower-alpha;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}

div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hlist td {
  padding-bottom: 15px;
}
td.hlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
}
td.hlist2 {
  vertical-align: top;
}

@media print {
  div#footer-badges { display: none; }
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-content {
  padding-left: 2.0em;
}

div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }

/* Because IE6 child selector is broken. */
div.olist2 ol {
  list-style-type: lower-alpha;
}
div.olist2 div.olist ol {
  list-style-type: decimal;
}
</style>
<title>PASA Data Adapter Cookbook</title>
</head>
<body>
<div id="header">
<h1>PASA Data Adapter Cookbook</h1>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="para"><p><strong>Writing your own data adapters is unnecessary if you wish to operate entirely using GFF3-formatted annotation files.  Building data adapters is only needed if you'd prefer to operate on alternatively formatted data files or to couple PASA directly to a relational database.  If the latter describes your interest, then keep reading&#8230;</strong></p></div>
<div class="para"><p>There are two primary forms of data adapters.  One is used to load the latest versions of annotations into the mysql database, and the other is to perform annotation updates based on the results of an annotation comparison.  The Data Adapters need to be implemented by the user, although sample implementations are available and described here.</p></div>
<div class="para"><p>Data Adapters, termed here as hooks, are Perl modules that implement abstract interfaces specific for each operation.  The $PASAHOME/pasa_conf/conf.txt file indicates the directory where these custom modules are to be located.  In our example $PASAHOME/pasa_conf/sample_test.conf file, we have the following line:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>HOOK_PERL_LIBS=__PASAHOME__/SAMPLE_HOOKS</tt></pre>
</div></div>
<div class="para"><p>which indicates that our example hooks are modules that are found in the $PASAHOME/SAMPLE_HOOKS directory.  The actual modules that implement the hooks are specified in the lines:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>HOOK_EXISTING_GENE_ANNOTATION_LOADER=GFF3::GFF3_annot_retriever::get_annot_retriever</tt></pre>
</div></div>
<div class="para"><p>and</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>HOOK_GENE_STRUCTURE_UPDATER=GFF3::GFF3_annot_updater::get_updater_obj</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">In addition to GFF3 format based data adapters, there are <a href="http://mblab.wustl.edu/GTF22.html">GTF</a> format data adapters as well.  In this case, you would use:
   HOOK_EXISTING_GENE_ANNOTATION_LOADER=GTF::Gtf_annot_retriever::get_annot_retriever
   HOOK_GENE_STRUCTURE_UPDATER=GTF::Gtf_annot_updater::get_updater_obj</td>
</tr></table>
</div>
</div>
</div>
<h2 id="_the_gene_annotation_loader_hook">The gene annotation loader hook</h2>
<div class="sectionbody">
<div class="para"><p>The <strong>HOOK_EXISTING_GENE_ANNOTATION_LOADER=GFF3::GFF3_annot_retriever::get_annot_retriever</strong> indicates that the module <strong>GFF3::GFF3_annot_retriever.pm</strong> found in the <strong>SAMPLE_HOOKS</strong> directory implements a method <strong>get_annot_retriever()</strong> which returns an object that inherits from and implements the functions of package <strong>PASA_UPDATES::Pasa_latest_annot_retrieval_adapter</strong>.  These details are important only if you decide that the provided data adapters are insufficient and you'd like to implement your own based on a different data file format or direct relational database connection.</p></div>
<h3 id="_importing_the_latest_annotations_into_the_pasa_database">Importing the latest annotations into the PASA database</h3><div style="clear:left"></div>
<div class="para"><p>In our example, we have our original annotations supplied in gff3 format, and our gene annotation loader hook implementing a gff3 file reader to supply the genome annotations.  We run the following script to load our annotations:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>% ../scripts/Load_Current_Gene_Annotations.dbi -c alignAssembly.config -g genome_sample.fasta -P orig_annotations_sample.gff3</tt></pre>
</div></div>
<div class="para"><p>The above script calls the gene annotation loader hook as specified in our sample conf.txt file.   The value provided to -P is provided as a parameter to the function called as the hook.  In this example, the paramter is the name of the gff3 file that contains the annotations.  In a different implementation of this hook (ie. at TIGR), this parameter is instead a set of values that are needed to connect to a relational database from which the annotations are extacted.</p></div>
<div class="para"><p>This system is designed to be flexible so that the annotations can be extracted from any source, relying on a custom implementation of the data adapter specified in the conf.txt file.  Sample GFF3 and GTF file format based data adapters are provided, and so custom data adapters may not be necessary.</p></div>
<h3 id="_performing_an_annotation_comparison">Performing an annotation comparison</h3><div style="clear:left"></div>
<div class="para"><p>The following command compares the loaded gene annotations to the PASA assemblies and performs updates to gene models.</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>% ../scripts/Launch_PASA_pipeline.pl -c annotCompare.config -A -g genome_sample.fasta -t all_transcripts.fasta.clean</tt></pre>
</div></div>
<div class="para"><p>Performing this step is essential and must be done prior to attempting to extract the updated gene structures using a data adapter, as described below.</p></div>
</div>
<h2 id="_the_gene_structure_updater_hook">The gene structure updater hook</h2>
<div class="sectionbody">
<div class="para"><p>Likewise, the <strong>HOOK_GENE_STRUCTURE_UPDATER=HOOK_GENE_STRUCTURE_UPDATER=GFF3::GFF3_annot_updater::get_updater_obj</strong> indicates that the module <strong>GFF3::GFF3_annot_updater.pm</strong> found in the <strong>SAMPLE_HOOKS</strong> directory implements a method <strong>get_update_obj()</strong> which returns an object that inherits from and implements the functions of package <strong>PASA_UPDATES::Pasa_update_adapter</strong>.</p></div>
</div>
<h2 id="_updating_our_gene_structure_annotations_via_a_data_adapter">Updating our gene structure annotations via a Data Adapter</h2>
<div class="sectionbody">
<div class="para"><p>After the annotation comparison, there will likely be some subset of PASA alignment assemblies that are classified as able to be successfully incorporated into gene structure annotations.  To extract these and perform updates, we need run the following script that calls the hook to the gene structure update adapter.</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>% ../scripts/cDNA_annotation_updater.dbi -M "${mysql_db_name}:${mysql_server_name}:${user}:${password}" -P null</tt></pre>
</div></div>
<div class="para"><p>By default, in our sample configuration file, the update adapter hook that is called is GFF3::GFF3_annot_updater::get_updater_obj.  If we needed to pass some critical piece of information to the hook, such as database connection parameters, we would do that thru the -P option of the script.  The example data adapter here does nothing but print the tentative successful gene structure updates to stdout in GFF3 format, and so we simply pass <em>null</em> to the -P option just so the parameter won't be empty.  In a more sophisticated setup, the successful annotation updates can be written back to the original annotation source, such as in a relational database.</p></div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2008-06-06 19:51:06 EDT
</div>
</div>
</body>
</html>
